home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.1 / xc.1 < prev    next >
Text File  |  1995-07-25  |  51KB  |  1,321 lines

  1. XC(L)                  XENIX/UNIX              (printed 3/11/94)
  2.  
  3. Name
  4.     xc - communications program
  5.  
  6. Syntax
  7.     xxxxcccc [----lllldevice] [----ssssscript    | ----tttt]
  8.  
  9. Description
  10.     XXXXcccc calls out over a serial port    to another computer. It    can manage an
  11.     interactive session or be called from ccccrrrroooonnnn(C).    It has various means
  12.     for transferring files between computers, and can be partially or
  13.     totally    under the control of scripts.
  14.  
  15.     XXXXcccc starts up by    reading    the file ._x_c, which is sought for in this
  16.     order: in "XC_PATH", in    the current directory, in your _H_O_M_E directory,
  17.     or in a    default    directory defined at compile time. This    startup    file
  18.     may contain any    of the valid _S_E_T commands described below. XXXXcccc then
  19.     displays the current settings, and presents an <_X_C> prompt, unless
  20.     either the ----tttt or ----ssss option was present.
  21.  
  22.    _O_p_t_i_o_n_s
  23.     ----llll_d_e_v_i_c_e Use the specified _d_e_v_i_c_e, which need not be the full pathname,
  24.          e.g. "/dev/tty1A" or "tty1A" are equally acceptable.  The line
  25.          could either be directly connected to another computer, or
  26.          have a    modem on it. In    either case (if    a value    was defined for
  27.          DIDO at compile time),    xxxxcccc attempts to suspend a ggggeeeettttttttyyyy(M) pro-
  28.          cess that might be on that line, and then use the uuuuuuuuccccpppp(C)
  29.          _L_C_K.._f_i_l_e mechanism to    lock the line.
  30.  
  31.     ----ssss_s_c_r_i_p_t Execute the specified _s_c_r_i_p_t after program startup.
  32.  
  33.     ----tttt     Go directly to    terminal mode. The default is to go to command
  34.          mode on program startup. This option is incompatible with the
  35.          ----ssss option.
  36.  
  37.    _E_n_v_i_r_o_n_m_e_n_t
  38.     If the environment contains a variable called "MODEM", then the    value
  39.     of that    variable will be the default device. As    with the ----llll flag, this
  40.     need not be the    full pathname. To set such a variable, in the Bourne
  41.     shell, you might say:
  42.  
  43.         MODEM=tty01; export MODEM
  44.  
  45.     or, in the C shell,
  46.  
  47.         setenv MODEM tty01
  48.  
  49.     If the environment contains a variable called "BYEttyxx", where    "ttyxx"
  50.     stands for the basename    of the modem line selected either by the MODEM
  51.     variable or by the "-l"    command    option,    then the value of that variable
  52.     will be    sent to    the modem when the program terminates. This is useful
  53.     for setting the    modem back to some preselected state. Example:
  54.  
  55.         BYEtty01=ATZ ; export BYEtty01
  56.  
  57.     Whatever string    is contained in    the "Byexxxxx" variable    will be    sent to
  58.     the modem preceded and followed    by a carriage-return.
  59.  
  60.     Newer modems can be preset to revert to    a predetermined    state when the
  61.     DTR signal of the computer is dropped, and so would not    need to    avail
  62.     themselves of this feature. Furthermore, ggggeeeettttttttyyyy programs    which have been
  63.     suspended, and which restart as    xxxxcccc exits, will reset a modem using
  64.     dialers    or chat    scripts    referred to in the /usr/lib/uucp/Devices file.
  65.  
  66.     The environment    may contain a variable called "XC_PATH", consisting of
  67.     colon separated    absolute paths to directories. If this variable    is set
  68.     to, say, "/usr/joe/xc:/usr/lib/xc", then those two directories are the
  69.     first places searched for any scripts.
  70.  
  71.  
  72.    _C_o_m_m_a_n_d _M_o_d_e
  73.     When entering characters in command mode (that is, at the <_X_C> prompt),
  74.     control    characters echo    as ^x, where "x" is the    control    character that
  75.     was entered. Backspacing (using    whatever key is    defined    in the current
  76.     environment) backspaces    over both positions of the displayed control
  77.     character, as expected.
  78.  
  79.     An "interpreted" key can be added in a manner similar to that of vvvviiii(C);
  80.     simply type ^V followed    by the character to insert (backspace, delete,
  81.     carriage return, or newline).
  82.  
  83.     The following commands are available at    the <_X_C> command prompt:
  84.  
  85.     cccc
  86.     cccciiiissss           Respond to an ENQ signal    for a CIS B-Plus protocol
  87.                transfer. This command is used for both uploading and
  88.                downloading from    CompuServe.
  89.  
  90.     dddd
  91.     ddddiiiiaaaallll           Enter the dial directory. Returns to the    <_X_C> prompt if
  92.                exited without dialing, but returns to terminal mode
  93.                after dialing or    running    a script.
  94.  
  95.     ssss _f_i_l_e
  96.     ssssccccrrrriiiipppptttt _f_i_l_e    Execute _f_i_l_e, which contains appropriate    xxxxcccc script com-
  97.                mands. Returns to terminal mode when the    script is com-
  98.                plete.
  99.  
  100.     rrrrbbbb _f_i_l_e           (XMODEM binary receive)
  101.     rrrrtttt _f_i_l_e           (XMODEM text receive) Receive _f_i_l_e from the remote sys-
  102.                tem.
  103.  
  104.     ssssbbbb _f_i_l_e           (XMODEM binary send)
  105.     sssstttt _f_i_l_e           (XMODEM text send) Transmit _f_i_l_e    to the remote system.
  106.  
  107.     sssseeeetttt [_o_p_t_i_o_n_s]  Display or set the transmission parameters used by xxxxcccc.
  108.                See below.
  109.  
  110.     tttt
  111.     tttteeeerrrrmmmm           Enter terminal mode.
  112.  
  113.     xxxx
  114.     qqqq
  115.     eeeexxxxiiiitttt
  116.     qqqquuuuiiiitttt           Exit program. Return to invoking    program/shell.
  117.  
  118.     hhhh
  119.     hhhhaaaannnngggguuuupppp           Hang-up the modem.
  120.  
  121.     %%%%pppp _l_o_c_a_l__n_a_m_e  [_r_e_m_o_t_e__n_a_m_e] Transmit (put) a file to a    remote Unix
  122.                system. This command uses standard Unix utilities on the
  123.                other end. _R_e_m_o_t_e__n_a_m_e defaults to the same pathname as
  124.                _l_o_c_a_l__n_a_m_e if not otherwise specified.
  125.  
  126.     %%%%tttt _r_e_m_o_t_e__n_a_m_e [_l_o_c_a_l__n_a_m_e] Receive (take) a file from a remote    Unix
  127.                system. This command uses standard Unix utilities on the
  128.                other end. _L_o_c_a_l__n_a_m_e defaults to the same pathname as
  129.                _r_e_m_o_t_e__n_a_m_e if not otherwise specified.
  130.  
  131.     ????
  132.  
  133.     hhhheeeellllpppp           Displays    a brief    summary    of xxxxcccc commands,    the SET
  134.                options,    and terminal-escape commands.
  135.  
  136.     [Note: a compile-time option can disable the following three options to
  137.     prevent    any access to shells or    other programs outside of xxxxcccc.]
  138.  
  139.     !!!! _c_o_m_m_a_n_d      Execute the specified _c_o_m_m_a_n_d as    a child    process. If
  140.                _c_o_m_m_a_n_d is omitted, execute a local interactive shell.
  141.                (A space    is required between the    !!!! and the _c_o_m_m_a_n_d.)
  142.  
  143.     !!!!!!!!           Re-execute the last shell command string.
  144.  
  145.     $$$$ _c_o_m_m_a_n_d      Execute a shell _c_o_m_m_a_n_d with stdin and stdout redirected
  146.                to the modem port. This effectively puts    the computer
  147.                into a "host" mode.  (A space is    required between the $$$$
  148.                and the _c_o_m_m_a_n_d.)
  149.  
  150.    _U_s_i_n_g _t_h_e _S_E_T _C_o_m_m_a_n_d
  151.     The _S_E_T    command    is used    to display and set/reset xxxxcccc's tunable parame-
  152.     ters. Any of these commands may    be placed in the ._x_c file which    is read
  153.     upon starting up xxxxcccc.
  154.  
  155.     Used alone, _S_E_T    displays xxxxcccc's current parameters.
  156.  
  157.     The following parameters can be    set (note that except in the case of
  158.     _n_a_m_es, these commands are case-_i_nsensitive, and    that there alternative
  159.     forms of the commands shown on the XC help screen):
  160.  
  161.     set auto on|off    Sets the auto-capture feature. When entering terminal
  162.             mode, capturing    commences without the necessity    to
  163.             manually request it.
  164.  
  165.     set bps    _v_a_l_u_e
  166.     set baud _v_a_l_u_e    Set the    desired    bits/second rate. Supported bps    rates
  167.             are 300, 1200, 2400, 9600 (and,    if included at compile
  168.             time, 19200 and    38400).
  169.  
  170.     set cfile _n_a_m_e    Set the    _n_a_m_e of    the capture file.
  171.  
  172.     set cis    on|off    Set response to    a CompuServe file transfer request
  173.             (<ENQ>). An "on" value specifies that when in terminal
  174.             mode, an <ENQ> character will launch a CIS B-Plus pro-
  175.             tocol transfer.    This parameter should be set "off"
  176.             when not connecting to CompuServe, as phone line noise
  177.             may cause a bogus file transfer    request.
  178.  
  179.     set cr on|off    In uploads using B-Plus    protocol, setting this option
  180.             "on" will insert a carriage-return after each newline
  181.             in an ASCII file. If you expect    your ASCII upload to
  182.             be captured by DOS users, it is    best to    set cr "on".
  183.             If your    ASCII upload is    meant strictly for Unix    users,
  184.             then you may set cr "off".  The    B-Plus protocol    imple-
  185.             mentation used by xxxxcccc will always strip end-of-line
  186.             carriage-returns from incoming ASCII files.
  187.  
  188.     set dir    _n_a_m_e    Set the    current    working    directory.
  189.  
  190.     set menu on|off    By default, a one-line menu is displayed above the
  191.             <_X_C> prompt to remind the user of options most fre-
  192.             quently    chosen at this point: "[d]ial directory
  193.             [t]erminal mode    [q]uit [s]cript    [?]help".  Setting the
  194.             option "off" turns off this display.
  195.  
  196.  
  197.  
  198.  
  199.     set nl on|off    If this    option is set "on", then newlines are sent as
  200.             carriage-returns. If this option is set    "off", then
  201.             newlines are sent as newlines (carriage-returns    are in
  202.             any case always    sent as    carriage-returns).  This
  203.             option applies to input    from the keyboard, or from a
  204.             disk file using    the "XXXXCCCCAAAAPPPPEEEE FFFF" facility or a script
  205.             "type" command (See below).  This option has no    effect
  206.             on built-in XMODEM or B-Plus protocol transmissions,
  207.             and has    no effect on incoming data.
  208.  
  209.     set pfile _n_a_m_e    Set the    _n_a_m_e of    the phone directory.
  210.  
  211.     set proto _v_a_l_u_e    This refers to the serial port character protocol, not
  212.             to a file transfer protocol. The possible values are
  213.             8N, 7E,    or 7O, (case insensitive) which    respectively
  214.             set the    modem port to a    character size of 8 with no
  215.             parity,    or a character size of 7 with either even or
  216.             odd parity. During B-Plus or XMODEM transfers, the
  217.             port protocol is set to    8N, and    reverts    to its prior
  218.             setting    thereafter.
  219.  
  220.     set xcape _c_h_a_r
  221.     set escape _c_h_a_r    Set the    XXXXCCCCAAAAPPPPEEEE character    (see below) to _c_h_a_r. This
  222.             should be set to some non-printing character (other
  223.             than backspace,    tab, newline, of course).  The charac-
  224.             ter may    be entered by depressing the Control key first
  225.             and then typing    a letter, or by    typing a carat (^)
  226.             followed by a letter.
  227.  
  228.     set xon    on|off
  229.     set xoff on|off    Set XON/XOFF flow control flag.    If "on", the program
  230.             will honor the XOFF control character and wait until
  231.             an XON character is received before transmitting any
  232.             more information. If "off", the    program    will ignore
  233.             XOFF/XON requests.
  234.  
  235.    _T_e_r_m_i_n_a_l _M_o_d_e
  236.     In terminal mode, all characters typed at the keyboard are sent    to the
  237.     modem, except that newline characters (0x0A) are translated to
  238.     carriage-returns (0x0D)    when you have "set nl 'on'"; all characters
  239.     received from the modem    are displayed on the local terminal screen.
  240.  
  241.     XXXXCCCCAAAAPPPPEEEE is a key that will, when typed in    terminal mode, introduce an xxxxcccc
  242.     "escape" command. Don't    confuse    XXXXCCCCAAAAPPPPEEEE with the <ESCAPE>    key.  The
  243.     default    definition for XXXXCCCCAAAAPPPPEEEE is    ASCII 1, or Control-A. It can be rede-
  244.     fined at run time with the "set    escape _C" command (or it can be    rede-
  245.     fined in the ._x_c startup script).
  246.  
  247.     When the XXXXCCCCAAAAPPPPEEEE key is typed in terminal    mode, the program will examine
  248.     the next key pressed. If this key has been "bound" to perform a    certain
  249.     function, that function    will be    performed; otherwise, the second char-
  250.     acter is sent to the modem. Thus, to send the XXXXCCCCAAAAPPPPEEEE character through
  251.     the modem, it is necessary to press the    key TWICE.
  252.  
  253.     Thus the ESCAPE    key itself would be a terrible choice for XXXXCCCCAAAAPPPPEEEE,
  254.     because    it is used so often by other programs: if you were logged into
  255.     a remote system    and running, say, vvvviiii, it would be a great annoyance to
  256.     have to    hit ESCAPE twice to get    it transmitted once.
  257.  
  258.     The following keys (case _i_nsensitive) are bound    at startup time. Others
  259.     may be added through the binding commands available in xxxxcccc scripts.
  260.  
  261.     Command     Function     Description
  262.  
  263.     XXXXCCCCAAAAPPPPEEEE ////     Help          Display the table    of bound keys
  264.     XXXXCCCCAAAAPPPPEEEE ????     Help          Display the table    of bound keys
  265.  
  266.     XXXXCCCCAAAAPPPPEEEE bbbb     _BREAK          Send a MODEM BREAK signal    (a sustained null).
  267.  
  268.     XXXXCCCCAAAAPPPPEEEE dddd     _Directory    Display the phone    directory.
  269.  
  270.     XXXXCCCCAAAAPPPPEEEE ffff     _File          Send a file through the modem (ASCII transfer).
  271.  
  272.     XXXXCCCCAAAAPPPPEEEE ssss     _Script          XXXXcccc will request the name of a script to execute.
  273.  
  274.     XXXXCCCCAAAAPPPPEEEE hhhh     _Hangup          Tell the modem to    go on-hook.
  275.  
  276.     XXXXCCCCAAAAPPPPEEEE yyyy     Capture _Yes  Open the capture file in APPEND mode (text
  277.                   received over the    port accumulates at the    end of
  278.                   the file). If the    file is    already    open, a    mes-
  279.                   sage is printed to that effect.
  280.  
  281.     XXXXCCCCAAAAPPPPEEEE nnnn     Capture _No   Close the    capture    file. If it wasn't open, a
  282.                   message of regret    is printed.
  283.  
  284.     XXXXCCCCAAAAPPPPEEEE xxxx     e_Xit          Exit terminal mode back to _<_X_C_> command mode.
  285.  
  286.     XXXXCCCCAAAAPPPPEEEE qqqq     _Quit          Quit xxxxcccc altogether.
  287.  
  288.    _P_h_o_n_e_l_i_s_t
  289.     XXXXcccc looks for a ._p_h_o_n_e_l_i_s_t file in the following    order: in the current
  290.     directory, in your home    directory as defined by    the $HOME environment
  291.     variable, or in    the LIBDIR as defined at compile time in _x_c._h. However
  292.     in command mode, any filename can be substituted, using    the SET    PFILE
  293.     command, so long as it has the following characteristics:
  294.  
  295.     It is ASCII text (lines    of text    separated by newlines).
  296.  
  297.     The first field    of data    in each    line (after any    whitespace and up to
  298.     the next occurence of whitespace) is a phone number in a valid format
  299.     for the    modem being used.
  300.  
  301.     Descriptive text may follow the    phone number. Spaces may be included in
  302.     this text, but a <TAB> must terminate this text.
  303.  
  304.     The following three definitions    may then follow    in any order:
  305.  
  306.     PROTO=sss   (sss=7e|7o|8n) Set the serial port protocol    for 7-bit char-
  307.             acters with    either even or odd parity, or for 8-bit    charac-
  308.             ters with no parity.
  309.  
  310.     BPS=nnnn    (n=300|1200|2400|9600|19200|38400) Set the bits/second rate
  311.             to the specified value.
  312.  
  313.     SCRIPT=file Immediately    after sending the autodial string, execute the
  314.             script file    specified. (Note that the specified filename is
  315.             CASE SENSITIVE!)
  316.  
  317.     The following definition, if used, must    be the LAST field on the line.
  318.  
  319.     PREFIX=xxxxxxxx    (e.g., PREFIX=ATs110=0s111=0)
  320.  
  321.     The PREFIX="string" allows you send your modem a different setup string
  322.     for each situation (default: no    special    setup).    This is    helpful    for MNP
  323.     and Telebit modems which require special attention for contacting non-
  324.     MNP modems and other Telebits.
  325.  
  326.    _S_c_r_i_p_t_s
  327.     The xxxxcccc script language is intended to be closely similar to the    Unix
  328.     Bourne shell language. Unfortunately, it isn't identical to the    Bourne
  329.     shell, so it has the same problem that the aaaawwwwkkkk(C) program does for
  330.     those experienced in the C language: an    aaaawwwwkkkk script LOOKS like C, but it
  331.     isn't, really; and in the same way, an xxxxcccc script LOOKS like a Bourne
  332.     shell script, but isn't. So the    operation of the Bourne    shell, if
  333.     you're familiar    with it, is useful as an analogy in understanding the
  334.     xxxxcccc script language, but    only as    an analogy.
  335.  
  336.     An xxxxcccc script consists of lists of commands. Commands are set off from
  337.     each other within a list by either a newline ('\n') or a semicolon (;),
  338.     as is the case with the    Bourne shell. The semicolon and    the newline
  339.     have identical effect as command separators, so    (anticipating a    bit
  340.     here) you could    say either
  341.  
  342.         if counter morethan    5
  343.         then
  344.            transmit    "bye^M"
  345.            quit
  346.         endif
  347.  
  348.     or
  349.  
  350.         if counter morethan    5; then    transmit "bye^M"; quit;    endif
  351.  
  352.     and the    result will be the same    either way. The    newline    and the    semi-
  353.     colon are treated the same way as in the Bourne    shell, except that a
  354.     newline    cannot be quoted so as to remove its interpretation as a com-
  355.     mand terminator    (in other words, a quoted string cannot    contain    a new-
  356.     line).
  357.  
  358.     Commands are composed of _w_o_r_ds separated by spaces or tab characters,
  359.     and a _w_o_r_d can be one of the following:
  360.  
  361.     *  One of the xxxxcccc script    language keywords, which are listed below, with
  362.        appropriate explanations.
  363.  
  364.     *  A number, meaning a sequence    consisting only    of digits, with    an
  365.        optional leading minus sign to indicate a negative number.
  366.  
  367.     *  A literal string of characters surrounded by    double-quotation marks
  368.        ('"'); such a string    can be no longer than 80 characters. A double-
  369.        quotation mark can be imbedded within the string by preceding it
  370.        with    a backslash ('\"'); when the string is interpreted, the
  371.        backslash is    disregarded and    the double-quotation mark is treated as
  372.        part    of the string. Mismatched quotation marks result in a syntax
  373.        error.
  374.  
  375.     *  The name of a user variable,    which can have either a    string or a
  376.        numeric value.  The name of a user variable must begin with an
  377.        alphabetic character.
  378.  
  379.     *  The name of a shell environment variable, preceded by a dollar sign
  380.        ('$'). The xxxxcccc script    language examines the Unix environment for the
  381.        specified variable and, if such a variable exists, substitutes the
  382.        value of that variable. The result is treated as if it were a quoted
  383.        literal string, and,    therefore, should not be more than 80 charac-
  384.        ters    long, or else it will be truncated to its first    80 characters.
  385.        Similarly, such an environment variable should not contain a    new-
  386.        line.
  387.  
  388.     *  An expression surrounded by back-quotation marks ('`'). This    sort of
  389.        expression operates similarly to the    Bourne shell's command-substi-
  390.        tution mechanism: the contents of the back-quotes are passed    to the
  391.        Bourne shell, and the standard output of the    back-quoted command is
  392.        treated as if it were a quoted literal string. Therefore, the
  393.        command's output should not be more than 80 characters long,    nor
  394.        contain a newline. Also, the    contents of the    back-quotes cannot be
  395.        longer than 80 characters, nor contain a newline.
  396.  
  397.     *  An expression introduced by a pound-sign (or    number-sign: '#'),
  398.        which is treated as a comment. All characters from the '#' until the
  399.        end of the physical line are    ignored. This comment mechanism    is the
  400.        same    as in the Bourne shell.
  401.  
  402.     *  A limitation    of the script language is that only one    character
  403.        string can be passed    as an argument to any of the script commands.
  404.        The _b_i_n_d__f_u_n_c_t_i_o_n, _b_i_n_d__s_c_r_i_p_t, and _b_i_n_d__s_t_r_i_n_g commands thus need
  405.        to use a decimal digit to represent the key that is to be bound. The
  406.        ASCII value of the the key is employed. As an example, Control-C is
  407.        identified as 3, Control-Z is 26, the ESCAPE    key is 27, a space is
  408.        32, the number "1" is 49; letters are case-_i_nsensitive so that iden-
  409.        tifying the bound key as "65" or as "97" will always    bind _b_o_t_h "a"
  410.        and "A" to the same command.
  411.  
  412.     Quoted literal strings (and the    two other mechanisms that act like
  413.     quoted literal strings,    shell environment variables and    back-quoted
  414.     shell commands)    may be up to 80    characters long. All other words must
  415.     be no longer than 16 characters, and are treated case-independently
  416.     (which is to say, uppercase is the same    as lowercase); note, though,
  417.     that the names of shell    environment variables are case-dependent
  418.     (uppercase must    match uppercase    and lowercase must match lowercase),
  419.     because    they are case-dependent    in the shell.
  420.  
  421.     Any word not recognizable within the foregoing categories is treated as
  422.     the name of a new user variable. Such a    word, if longer    than 16    charac-
  423.     ters, is considered to be a syntax error.
  424.  
  425.     User variables are created with    the 'assign' script keyword, and may
  426.     have either numeric or string values. The type of a user variable is
  427.     determined by how it's created;    if it's    assigned to a string, it's a
  428.     string variable, and if    it's assigned to a number, it's    a numeric vari-
  429.     able. The value    of any user variable can be changed with another
  430.     'assign' command, and numeric variables    can be changed to string vari-
  431.     ables and vice-versa. Shell environment    variables cannot be changed
  432.     within an xxxxcccc script, but the value of a    shell environment variable can
  433.     be assigned to a user variable,    and the    value of the user variable can
  434.     thereafter be changed.
  435.  
  436.     Scripts    are contained in ASCII text disk files,    one script to a    file. A
  437.     script can invoke another script as a subroutine with the 'call' key-
  438.     word; up to 5 scripts can be nested in this way    at any single time.
  439.  
  440.     With all this said, the    following list of xxxxcccc script language commands
  441.     should be comprehensible. The format "<something>" means that a    token,
  442.     or word-type, of the "something" type is meant rather than the literal
  443.     sequence 'something'.
  444.  
  445.    _S_c_r_i_p_t _L_a_n_g_u_a_g_e _C_o_m_m_a_n_d_s
  446.     Note that all the commands are case-_i_nsensitive!
  447.  
  448.     _a_f_f_i_r_m
  449.         Syntax: affirm
  450.  
  451.         Reads a string from    the terminal, and returns TRUE if the string
  452.         begins with    'y' or 'Y'; otherwise, returns FALSE.  Used in evaluat-
  453.         ing    conditional expressions. The string must be terminated by a
  454.         newline or carriage-return.
  455.  
  456.         Example:
  457.  
  458.         echo -n    "Continue (y/n)? "
  459.         if affirm
  460.         then
  461.             continue
  462.         else
  463.             break
  464.         endif
  465.  
  466.     _a_s_s_i_g_n
  467.         Syntax: assign <varname> eq    <number>
  468.             assign <varname> eq    "string"
  469.             assign <varname1> eq <varname2>
  470.             assign <varname> eq    <script-command>
  471.  
  472.         Assigns to user variable <varname> the value following "eq"; if
  473.         that value is a number, then <varname> becomes a numeric user vari-
  474.         able; if that value    is a string, then <varname> becomes a string
  475.         user variable. If <varname>    does not already exist as a user vari-
  476.         able, it is    created. Variable space    is allocated dynamically, but
  477.         running out    of memory space    for variables is unlikely. All vari-
  478.         ables are global across scripts that run at    the same time via the
  479.         'call' keyword, and    all variables vanish when a script, called
  480.         directly from xxxxcccc as    opposed    to called from another script, exits.
  481.         In other words, variable values are    not static except during 'call'
  482.         execution. Variable    names cannot be    longer than 8 characters. Suc-
  483.         cessive 'assigns' are permissible, and the type of the variable
  484.         changes according to the type of the value following "eq". A user
  485.         variable is    destroyed with the 'unassign' keyword.
  486.  
  487.         If a variable is assigned the value    of a script command, then it
  488.         becomes a numeric variable with value TRUE or FALSE, depending on
  489.         the    status returned    by the script command. If a variable is
  490.         assigned the value of a back-quoted    command, it becomes a string
  491.         variable with the value of the first 80 characters of the back-
  492.         quoted command. If a variable is assigned equal to an environment
  493.         variable, it becomes a string variable with    the value of the first
  494.         80 characters of the value of the environment variable.
  495.  
  496.         Examples:
  497.  
  498.         assign numvar eq 5
  499.         assign strvar eq "This variable    is a string"
  500.         assign mydir eq    $HOME
  501.         assign numvar2 eq numvar
  502.         assign strvar2 eq strvar
  503.         assign numvar eq true
  504.         assign today eq    `date`;    echo "today is " today
  505.  
  506.     _b_e_e_p
  507.         Syntax: beep
  508.  
  509.         Sends a Control-G to the terminal. Useful for alerting the user
  510.         that some event has    occurred, for example a    CONNECT    after a    lengthy
  511.         redialing session.
  512.  
  513.     _b_i_n_d__f_u_n_c_t_i_o_n
  514.         Syntax: bind_function _c_o_d_e "function"
  515.  
  516.         Bind the character identified by the number    specified by _c_o_d_e to
  517.         the    xxxxcccc builtin function "function".
  518.  
  519.         The    "function" may be one of the following (case is    ignored):
  520.  
  521.         BRKCHAR     Send modem BREAK signal
  522.         CAPTEND     Turn off terminal mode    capture
  523.         CAPTYES     Turn on terminal mode capture
  524.         DIALCHR     Dial from phonelist
  525.         DIVCHAR     Send file through modem
  526.         DOSCRPT     Execute script    file (prompts interactively)
  527.         EMITSTR     Emit string
  528.         ENDCHAR     Exit terminal mode
  529.         HLPCHAR     Display terminal mode key bindings
  530.         HUPCHAR     Hang up modem
  531.         QUITCHR     Quit program
  532.         SCRPCHR     Prompt    for script file
  533.  
  534.         Example:
  535.  
  536.         bind_function 26 "quitchr"
  537.  
  538.         This binds Control-Z to quit the XC    program.
  539.  
  540.     _b_i_n_d__s_c_r_i_p_t
  541.         Syntax: bind_script    _c_o_d_e "scriptname"
  542.  
  543.         Bind the character identified by the number    specified by _c_o_d_e to
  544.         execute the    script named by    "scriptname".
  545.  
  546.         Upon termination of    the script, the    program    will resume terminal
  547.         mode, unless the "quit" script function was    executed.
  548.  
  549.         Examples:
  550.  
  551.         bind_script 18 "/usr/lib/xc/.rz"
  552.  
  553.         This binds Control-R to execute the    script /usr/lib/xc/.rz.    The .rz
  554.         script supplied with the source code contains:
  555.  
  556.         tty "on"
  557.         echo -n    "What files are    to be received?    "
  558.         read FILES
  559.         transmit "sz -y    "
  560.         transmit FILES
  561.         transmit "^M"
  562.         echo "Starting ZMODEM Receive (rz -y)"
  563.         pipe "rz -y"
  564.  
  565.         Pressing XXXXCCCCAAAAPPPPEEEE ^^^^RRRR will ask for some    file name(s), and start    an sssszzzz
  566.         command on the remote system, and an rrrrzzzz on the local system    to
  567.         receive the    file(s).
  568.  
  569.         bind_script 19 "/usr/lib/xc/.sz"
  570.  
  571.         This binds Control-S to execute the    script /usr/lib/xc/.sz.    The .sz
  572.         script supplied with the source code contains:
  573.  
  574.         tty "on"
  575.         echo -n    "What files are    to be sent? "
  576.         read FILES
  577.         echo "Starting ZMODEM send (sz -y " FILES ")"
  578.         pipe "sz -y " FILES
  579.  
  580.         Pressing XXXXCCCCAAAAPPPPEEEE ^^^^SSSS will ask for some    file name(s), and then launch
  581.         sssszzzz on the current system.  SSSSzzzz will itself start an rrrrzzzz process on
  582.         the    remote system.
  583.  
  584.  
  585.     _b_i_n_d__s_t_r_i_n_g
  586.         Syntax: bind_string    _c_o_d_e "string"
  587.  
  588.         Bind the character identified by the number    specified by _c_o_d_e to
  589.         emit the string specified by "string".
  590.  
  591.         The    string is sent to the modem untranslated; eg, it is not    exam-
  592.         ined for embedded terminal mode escapes.
  593.  
  594.         Example:
  595.  
  596.         bind_string 49 "AAATZ^M"
  597.  
  598.         This binds "1" to send the sequence    to reset the modem.
  599.  
  600.     _b_r_e_a_k
  601.         Syntax: break
  602.  
  603.         Exits from the immediately enclosing 'while' loop. Identical to the
  604.         C language 'break',    and to the Bourne shell    'break'    except that the
  605.         xxxxcccc script language 'break' does not    take a numeric argument. Don't
  606.         confuse this with the script keyword 'xmitbrk', which sends    a BREAK
  607.         signal to the modem    port.
  608.  
  609.     _c_a_l_l
  610.         Syntax: call "scriptname"
  611.  
  612.         Suspends execution of the current script, and attempts to load and
  613.         run    the specified scriptname. The scriptname must be a quoted
  614.         literal string. There is no    xxxxcccc analogue of the Bourne shell    "exec"
  615.         command; all subscripts in xxxxcccc are treated as sub-routines. All
  616.         variables are global across    subscripts, so if a subscript changes
  617.         the    value of a variable, then that change will remain in effect
  618.         after return to the    parent script. Shell environment variables can-
  619.         not    be changed by any xxxxcccc script.
  620.  
  621.     _c_a_p_t_u_r_e
  622.         Syntax: capture "on"
  623.             capture "off"
  624.  
  625.         Turns the file-capture function on or off. Note that the arguments
  626.         must be quoted literal strings. Note also that when    the script
  627.         exits into terminal    mode, the file-capture function    is turned off.
  628.         If you have    'set auto "on"', then you will begin capturing immedi-
  629.         ately upon entering, or returning to, terminal mode. If not, then
  630.         you    must manually type "XXXXCCCCAAAAPPPPEEEE YYYY" to    start capturing    when entering
  631.         terminal mode.
  632.  
  633.     _c_o_n_t_i_n_u_e
  634.         Syntax: continue
  635.  
  636.         Resumes execution at the top of the    immediately enclosing 'while'
  637.         loop.  Identical to    the C language 'continue' instruction, and to
  638.         the    Bourne shell 'continue'    command    except that no numeric argument
  639.         is accepted.
  640.  
  641.     _d_e_b_u_g
  642.         Syntax: debug "on"
  643.             debug "off"
  644.  
  645.         If the 'debug' option is on, then xxxxcccc will make many    parenthetical
  646.         comments about what    it's doing while it runs the script. These com-
  647.         ments can sometimes    be helpful in debugging    script logic. Note that
  648.         the    argument must be a quoted literal string.
  649.  
  650.         While debugging a script containing    a password, turn this option
  651.         off, then on again,    to reduce the excitement-level of any col-
  652.         leagues collected circa your screen.
  653.  
  654.     _d_e_c_r
  655.         Syntax: decr <numeric-variable>
  656.  
  657.         Decrements the value of the    specified numeric user variable    by 1.
  658.         Useful in controlling loop execution. If the specified variable
  659.         isn't numeric, or doesn't exist, a syntax error results.
  660.  
  661.     _d_i_a_l
  662.         Syntax: dial "number-string"
  663.  
  664.         Dials the specified    number,    using modem-command strings defined in
  665.         xc.h.  The number should not contain spaces; dashes    are acceptable.
  666.  
  667.     _e_c_h_o
  668.         Syntax: echo "string" <variable> ...
  669.             echo -n "string" <variable>    ...
  670.  
  671.         This command sends its arguments to    the user's terminal. The number
  672.         of arguments is optional, except that the total result may not
  673.         exceed 80 characters. Variables and    back-quoted shell commands are
  674.         expanded as    necessary.
  675.  
  676.         If the "-n"    switch is present, then    no carriage-return/newline
  677.         sequence is    appended to the    output.
  678.  
  679.         Examples:
  680.  
  681.         echo "The time and date    are now    " `date`
  682.         echo "My terminal type is " $TERM
  683.         echo "My terminal type is " $TERM " today."
  684.  
  685.         Note that whitespace isn't echoed unless it's part of a quoted
  686.         literal string.
  687.  
  688.     _e_x_i_t
  689.         Syntax: exit
  690.  
  691.         Terminates execution of the    current    script.    If a script reaches its
  692.         end, it exits automatically, so 'exit' is useful mainly to ter-
  693.         minate a script prematurely.
  694.  
  695.     _f_a_l_s_e
  696.         Syntax: false
  697.  
  698.         Same as the    Unix 'false' command. Does nothing, but    returns    a FALSE
  699.         status value. Useful within    conditional expressions.
  700.  
  701.         Example:
  702.  
  703.         if waitfor "CONNECT" 30    eq false
  704.         then
  705.             quit
  706.         endif
  707.  
  708.         Note that above example could be rewritten using the negating
  709.         modifier "!":
  710.  
  711.         if ! waitfor "CONNECT" 30
  712.         then
  713.             quit
  714.         endif
  715.  
  716.         and    note too that the "!" must be separated    from its argument by
  717.         whitespace.
  718.  
  719.     _f_i_l_e
  720.         Syntax: file <script-command>
  721.  
  722.         The    standard output    of the specified script    command    is sent    to the
  723.         current capture file. If the "capture" option is not set, then an
  724.         error message is displayed,    but script execution continues.
  725.  
  726.         Examples:
  727.  
  728.         file echo "--------- CUT HERE ----------"
  729.  
  730.         Sends the output of    the 'echo' command to the current capture file,
  731.         provided that the "capture"    option is now "on".
  732.  
  733.         file echo `date`
  734.  
  735.         Sends a timestamp to the current capture file, provided that the
  736.         "capture" option is    now "on". The same thing could have been done
  737.         with
  738.  
  739.            file shell "date"
  740.  
  741.  
  742.     _h_a_n_g_u_p
  743.         Syntax: hangup
  744.  
  745.         Tells the modem to go on-hook.
  746.  
  747.  
  748.     _i_f
  749.         Syntax: if <list1>;    then <list2>; [    else <list3>; ]    endif
  750.  
  751.         If <list1> evaluates as TRUE, performs <list2>; otherwise, if
  752.         <list3> is specified, performs <list3>; then resumes execution
  753.         immediately    following 'endif'. To accommodate those    whose minds
  754.         wander while writing scripts, 'fi' is an acceptable    synonym    for
  755.         'endif'.
  756.  
  757.         Each list may consist of any number    of script commands separated by
  758.         semicolons or newlines. The    value of <list1> is determined by
  759.         inclusively    OR'ing the value of each directive in the list,    so that
  760.         if any of the directives in    <list1>    evaluates as TRUE, then    so will
  761.         <list1>. <list1> is    performed in its entirety regardless of    the
  762.         value of any of its    component commands.
  763.  
  764.         The    keywords 'then', 'else', and 'endif' (or 'fi') must be immedi-
  765.         ately preceded by command separators, either a semicolon or    a new-
  766.         line, just as is the case in the Bourne shell.
  767.  
  768.         For    conditional evaluation in 'if' and 'while' constructions, the
  769.         following comparators are available    in addition to the script
  770.         directives mentioned elsewhere:
  771.  
  772.         <varname1> eq "string"
  773.         <varname1> eq <number>
  774.         <varname1> eq <varname2>
  775.         <varname1>
  776.         "string"
  777.  
  778.         evaluates as TRUE if the value of user variable <varname1> is the
  779.         same as that of a specified    string or numeric constant or of a
  780.         specified second variable name. If the variable name <varname1> is
  781.         not    followed by anything else, then    the expression evaluates as
  782.         TRUE if the    variable is numeric and    has a non-zero value, or if the
  783.         variable is    a string variable and has a non-zero length; otherwise,
  784.         the    expression evaluates as    FALSE. Comparing a string variable to a
  785.         numeric variable, or vice-versa, causes a syntax error.
  786.  
  787.         If a conditional expression    consists only of a quoted literal
  788.         string, the    expression evaluates as    TRUE if    the string's length is
  789.         non-zero, and otherwise evaluates to FALSE.    Because    environment
  790.         variables and back-quoted shell commands are treated as if their
  791.         output/value were quoted literal strings, this allows direct test-
  792.         ing    of a shell command or of an environment    for non-zero length.
  793.         Nonexistent    environment variables are treated as if    they exist with
  794.         the    value "" (a string of zero length).
  795.  
  796.         <varname1> neq "string"
  797.         <varname1> neq <number>
  798.         <varname1> neq <varname2>
  799.  
  800.         evaluates as TRUE if the value of user variable <varname1> is not
  801.         equal to that of a specified string    or numeric constant or of a
  802.         specified second variable name. Comparing a    string variable    to a
  803.         numeric variable, or vice-versa, causes a syntax error.
  804.  
  805.         <varname1> lessthan "string"
  806.         <varname1> lessthan <number>
  807.         <varname1> lessthan <varname2>
  808.  
  809.         evaluates as TRUE if the value of user variable <varname1> is less
  810.         than that of a specified string or numeric constant    or of a    speci-
  811.         fied second    variable name.    String variables are compared lexically
  812.         according to ASCII value.
  813.  
  814.         <varname1> morethan "string"
  815.         <varname1> morethan <number>
  816.         <varname1> morethan <varname2>
  817.  
  818.         operates identically to 'lessthan',    except in reverse.
  819.  
  820.         The    value of any conditional expression may    be negated by preceding
  821.         it with an exclamation point followed by a space or    tab.
  822.  
  823.         Examples:
  824.  
  825.         if counter eq 0; then break; endif;
  826.         if var1    eq var2; then echo "identical";    endif
  827.         if counter morethan 20;    then break; endif;
  828.         if counter lessthan 0; then break; endif;
  829.         if ! counter; then echo    "counter is " counter; endif
  830.  
  831.         To perform a list if any of    a set of conditions exist:
  832.  
  833.         if counter morethan 5;
  834.             counter eq brkvalue;    # a    second comparator
  835.         then break;
  836.         endif;
  837.  
  838.         i.e., perform the 'break' directive    if the value of    numeric    user
  839.         variable 'counter' is greater than the numeric constant 5, or if
  840.         the    value of 'counter' is equal to that of the user    numeric    vari-
  841.         able 'brkvalue'.
  842.  
  843.     _i_n_c_r
  844.         Syntax: incr <numeric-variable>
  845.  
  846.         Increments the value of the    specified numeric user variable    by 1.
  847.         The    opposite of 'decr'.
  848.  
  849.     _l_i_n_k_e_d
  850.         Syntax: linked
  851.  
  852.         'linked' is    a pseudo-function that evaluates as TRUE if the    current
  853.         script has been invoked from the dialing directory,    and as FALSE
  854.         otherwise.
  855.  
  856.         Example:
  857.  
  858.         if ! linked; then
  859.             dial "5551212"
  860.         endif
  861.  
  862.     _p_a_u_s_e
  863.         Syntax: pause <number>
  864.  
  865.         Suspends execution for the specified <number> of SECONDS. Identical
  866.         to Unix "sleep."
  867.  
  868.     _p_i_p_e
  869.         Syntax: pipe "<shell-command>"
  870.  
  871.         The    standard input and standard output of the specified shell com-
  872.         mand are connected to the modem port, and the command is executed.
  873.         This is the    equivalent of the command mode "$" command.
  874.  
  875.         Examples:
  876.  
  877.         pipe "echo \"\177\""
  878.  
  879.         sends a DELETE character to    the modem.
  880.  
  881.         pipe "rz"
  882.  
  883.         performs a file receive via    ZMODEM,    assuming that Chuck Forsberg's
  884.         'rz/sz' programs reside on your system.
  885.  
  886.  
  887.     _p_o_r_t_n_a_m_e
  888.         Syntax: portname
  889.  
  890.         This isn't a command, but a    synonym    for the    current    modem terminal
  891.         device, treated as if it were a quoted string. Useful if modems of
  892.         differing types are    attached to different terminal lines and need
  893.         different dialing or initialization    sequences. To compare the value
  894.         of 'portname' to some other    string,    you must first assign a    user
  895.         variable equal to 'portname'.
  896.  
  897.         Examples:
  898.  
  899.         assign myport eq portname
  900.         if myport eq "/dev/tty01"
  901.         then
  902.             transmit "AT&E0^M"
  903.         endif
  904.  
  905.     _q_u_i_t
  906.         Syntax: quit
  907.  
  908.         Exits the script and terminates xxxxcccc entirely. Any LCKfile will be
  909.         removed if possible    and the    user's terminal    will be    restored to the
  910.         state it was in when xxxxcccc was    invoked.
  911.  
  912.     _r_e_a_d
  913.         Syntax: read <variable-name>
  914.  
  915.         Takes a string from    the user's keyboard and    places it into the
  916.         specified user variable. Any previous value    of the specified vari-
  917.         able is discarded.
  918.  
  919.     _r_e_d_i_a_l
  920.         Syntax: redial
  921.  
  922.         Redials the    number most recently dialed with the 'dial' command.
  923.  
  924.     _s_e_e_n
  925.         Syntax: seen "string" <number>
  926.  
  927.         Evaluates as TRUE if "string" has occurred within the last <number>
  928.         characters received    during the most    recent 'waitfor' command. Only
  929.         up to 2048 characters are remembered at any    one time during    'wait-
  930.         for' processing. If    no <number> is specified, then all the charac-
  931.         ters received during the most recent 'waitfor' command are exam-
  932.         ined, up to    a maximum of 2048. The 'seen' buffer is    reset at the
  933.         beginning of each 'waitfor'    command. This is useful    to tell    which
  934.         of several strings has been    received.
  935.  
  936.         Example:
  937.  
  938.         if waitfor "string1" 20
  939.         then
  940.             echo "Received 'string1'."
  941.         else
  942.             if seen "string2"
  943.             then
  944.             echo "Received 'string2' instead."
  945.             endif
  946.         endif
  947.  
  948.     _s_e_t
  949.         Syntax: set    <xxxxcccc-set-option>    <value>
  950.  
  951.         This command is the    same as    the command-mode xxxxcccc 'set' command, such
  952.         as "set bps    1200", "set cis    on", and so forth, except that a string
  953.         <value> must be enclosed within double-quotation marks.
  954.  
  955.         Examples:
  956.  
  957.         set cis    "on"
  958.         set cfile "newfilename"
  959.         set auto "on"
  960.         set bps    2400
  961.  
  962.     _s_h_e_l_l
  963.         Syntax: shell "<shell-command>"
  964.  
  965.         The    shell command enclosed within the double-quotation marks is
  966.         executed. This is similar to the xxxxcccc    command-mode "!" command.
  967.         Remember that if the shell command contains    double-quotation marks,
  968.         they must be escaped with backslashes.
  969.  
  970.     _t_i_m_e_o_u_t
  971.         Syntax: timeout <number>
  972.  
  973.         If <number>    is greater than    zero, starts a timer which will    cause
  974.         the    MOST DEEPLY NESTED script to exit when <number>    of MINUTES
  975.         expire. If <number>    is zero, then any pending timeout is cancelled.
  976.         If <number>    is negative, nothing happens.
  977.  
  978.         Expiration of the specified    timeout    causes the most    deeply nested
  979.         script to exit, not    to terminate xxxxcccc.  To cause the program to quit
  980.         if a timeout expires, use a    subscript.
  981.  
  982.         Example:
  983.  
  984.         'script1' contains:
  985.  
  986.             call "script2"
  987.             if expired
  988.             then
  989.             quit
  990.             endif
  991.             # more commands
  992.  
  993.  
  994.         'script2' contains:
  995.  
  996.             assign expired eq 1
  997.             timeout 5        # limit    of 5 minutes
  998.             while ! waitfor "login:" 30
  999.             do
  1000.             xmitbrk
  1001.             done
  1002.             assign expired eq 0
  1003.             exit
  1004.  
  1005.         When 'script2' exits, the numeric variable 'expired' will be set to
  1006.         1 if 'script2' timed out, and will be 0 otherwise. 'script1' can
  1007.         act    on this    information accordingly.
  1008.  
  1009.     _t_r_a_n_s_m_i_t
  1010.         Syntax: transmit "string"
  1011.  
  1012.         Sends a string to the modem. The string is sent with brief pauses
  1013.         between characters,    to accommodate modems that cannot accept rapid
  1014.         command input, and within the string, any alphabetic character pre-
  1015.         ceded by a caret (^) is translated to the corresponding Control-
  1016.         character.
  1017.  
  1018.         Example:
  1019.  
  1020.         transmit "ATDT 5551212^M"
  1021.  
  1022.         sends the string "ATDT 5551212" to the modem, followed by a
  1023.         carriage-return character.
  1024.  
  1025.     _t_r_u_e
  1026.         Syntax: true
  1027.  
  1028.         Does nothing, but always evaluates as TRUE.    Useful in conditional
  1029.         expressions. The opposite of 'false'.
  1030.  
  1031.     _t_t_y
  1032.         Syntax: tty    "on"
  1033.             tty    "off"
  1034.  
  1035.         Ordinarily,    during script execution, characters received from the
  1036.         modem port are echoed to the user's    terminal screen. This happens
  1037.         only during    'waitfor' and 'type' execution,    so it may be a bit
  1038.         choppy. This echoing can be    turned off with
  1039.  
  1040.         tty "off"
  1041.  
  1042.         and    turned back on with
  1043.  
  1044.         tty "on"
  1045.  
  1046.         Note that "on" and "off" must be enclosed in quotation marks.
  1047.  
  1048.     _t_y_p_e
  1049.         Syntax: type "<filename>"
  1050.  
  1051.         Sends the specified    ASCII file to the modem    port. This is the same
  1052.         as the xxxxcccc terminal-mode "send ASCII    file" escape.
  1053.  
  1054.     _u_n_a_s_s_i_g_n
  1055.         Syntax: unassign <variablename>
  1056.  
  1057.         Erases the specified user variable.    The variable may be either
  1058.         numeric or string type. The    variable name must not be enclosed in
  1059.         quotation marks, because variable names are    considered to be xxxxcccc
  1060.         script keywords, and not literal strings.
  1061.  
  1062.     _w_a_i_t_f_o_r
  1063.         Syntax: waitfor "string" <number>
  1064.  
  1065.         Scans input    from the modem port for    an occurrence of the specified
  1066.         string, which must be enclosed in quotation    marks. The scanning
  1067.         continues for the specified    <number> of SECONDS or until the speci-
  1068.         fied string    is identified in the modem input stream, whichever
  1069.         comes first. This command evaluates    as TRUE    if the specified string
  1070.         is found, and as FALSE if the specified <number> of    SECONDS    elapses
  1071.         and    the string isn't found within that time. The default time, if
  1072.         no <number>    is specified, is roughly 30 seconds.
  1073.  
  1074.         String matching is performed on a case-_i_nsensitive basis.  Within
  1075.         the    string,    any alphabetic character preceded by a caret (^) is
  1076.         translated to the corresponding Control-character.
  1077.  
  1078.         Examples:
  1079.  
  1080.         assign counter eq 1
  1081.         while !    waitfor    "login:" 15
  1082.         do
  1083.             xmitbrk; incr counter; if counter morethan 5
  1084.             then
  1085.             quit
  1086.             endif
  1087.         done
  1088.  
  1089.         If in a CompuServe Forum the "prompt character" has    been set by the
  1090.         user to be a backspace, this test will log off if the main prompt
  1091.         is not seen    in the next sixty seconds:
  1092.  
  1093.         if ! waitfor "forum !^H" 60
  1094.         then
  1095.             transmit "bye^M"; quit
  1096.         endif
  1097.  
  1098.         If the 'cis' option    has been set to    "on", either in    the ._x_c    startup
  1099.         script, or by a direct 'set' command from command mode, or with
  1100.  
  1101.         set cis    "on"
  1102.  
  1103.         within a current script, and if during 'waitfor' processing    a CIS
  1104.         B-Plus protocol file transfer request is received, then the    B-Plus
  1105.         protocol transfer is performed, the    <number> argument is reset to
  1106.         its    original value,    and 'waitfor' processing continues. This allows
  1107.         automatic B-Plus protocol file transfers from within a script.
  1108.  
  1109.     _w_h_i_l_e
  1110.         Syntax: while <list1>; do <list2>; done
  1111.  
  1112.         Operates similarly to the 'if' command, except that    <list2>    is exe-
  1113.         cuted repeatedly so    long as    <list1>    evaluates as TRUE. All the con-
  1114.         ditional comparators and rules for comparisons that    apply for the
  1115.         'if' command also apply to 'while'.    (Note that 'while' loops can be
  1116.         nested within 'if' commands    and vice-versa.)
  1117.  
  1118.     _x_m_i_t_b_r_k
  1119.         Syntax: xmitbrk
  1120.  
  1121.         Sends a BREAK signal to the    modem port.
  1122.  
  1123.    _F_i_l_e    _T_r_a_n_s_f_e_r_s
  1124.     When transferring files    using the XMODEM protocol, the file mode is
  1125.     specified in the upload/download command. A TEXT mode transfer enables
  1126.     translation of the transmitted or received file    to support CP/M    and
  1127.     MS-DOS end-of-line characters.    When transmitting a file using TEXT
  1128.     mode, all newlines are converted to carriage-return/newline sequences.
  1129.     When receiving a file using TEXT mode, all carriage-return/newline
  1130.     sequences are converted    to just    a newline. A BINARY mode transfer
  1131.     transmits the file "as is" without any such conversion.
  1132.  
  1133.     When transferring files    using CompuServe B-Plus    protocol, the format of
  1134.     the file is specified by the host. An ASCII mode will force xxxxcccc to per-
  1135.     form TEXT mode translation; a BINARY mode will not do any translation.
  1136.     This means that, in either direction, a    BINARY mode will send bytes "as
  1137.     is", whereas in    ASCII mode, an incoming    file will always be stripped of
  1138.     end-of-line carriage-returns, while an ASCII file being    uploaded may or
  1139.     may not    have carriage-returns added after each newline,    depending on
  1140.     the "on" or "off" setting of the "cr" option.
  1141.  
  1142.     When using either the "%t" (take) command, an XMODEM receive command,
  1143.     or a CompuServe    B-Plus download    command, xxxxcccc will check if the file name
  1144.     you specify already exists on your system, and ask for an OK to
  1145.     overwrite the file, or for an alternative name.    In the CompuServe case,
  1146.     there will also    be an option to    "Resume" a download. If    the CRC    check-
  1147.     sum of the bytes that you already have in the file matches CompuServe's
  1148.     checksum on the    the same initial bytes in its version of the file, file
  1149.     transfer will proceed from that    point onwards. This saves connect time
  1150.     when a very large download has been interrupted    during a prior session.
  1151.  
  1152.     Script-driven file transfers using the CompuServe B-Plus protocol are
  1153.     more or    less built into    the xxxxcccc script language,    since during 'waitfor'
  1154.     processing, a file transfer request from the modem port    will trigger a
  1155.     B-Plus transfer    if the "cis" mode is set.  The difficulty in performing
  1156.     such transfers isn't in    the transfer itself, but rather    in the
  1157.     maneuvering required to    get into position to transfer the correct file,
  1158.     and is something that probably only experienced    script writers should
  1159.     wrestle    with. However, if we assume that in the    midst of a script,
  1160.     you've reached a point where you can issue a "download"    command    to Com-
  1161.     puServe, for instance a    "Disposition" prompt during a File Library
  1162.     "BROWSE" command, and you want to download the present file, which is
  1163.     "XCALL.C" on CompuServe, and "xcall.c" does not    exist in your current
  1164.     working    directory, you'd use the following sequence of script commands
  1165.     to do it:
  1166.  
  1167.         set    cis on         # can't do    auto file B-Plus transfer otherwise
  1168.         transmit "dow^M"
  1169.         pause 2         # wait for    CIS to display protocol    menu
  1170.         transmit "2^M"   # B-Plus is number    2 on that menu
  1171.         transmit "xcall.c^M"  # "file name for your    computer:"
  1172.         waitfor "Disposition"
  1173.  
  1174.     During the final "waitfor" processing, the CompuServe ENQ character
  1175.     will be    recognized and the transfer will proceed automatically.    Then
  1176.     'waitfor' will continue    waiting    for the    "Disposition" prompt, after
  1177.     which your script can proceed. The same    sort of    thing can be done with
  1178.     file uploads, but once again, the difficulty isn't with    the transfer,
  1179.     but rather with    setting    things up so that the transfer will be
  1180.     requested at the correct place.
  1181.  
  1182.     A shell    script,    cccciiiissssddddoooowwwwnnnnllllooooaaaadddd provided with the distribution, can
  1183.     automatically retrieve a single    file from a CompuServe library.
  1184.  
  1185.     For XMODEM, YMODEM, and    ZMODEM transfers via scripts, there's no
  1186.     mechanism built    into the xxxxcccc script language to use the built-in, 128-
  1187.     byte-packet XMODEM in xxxxcccc.  Instead, we strongly    recommend that you
  1188.     obtain Chuck Forsberg's    excellent, shareware utility called "RZSZ",
  1189.     which can handle XMODEM, XMODEM-1K, YMODEM, and    ZMODEM transfers and
  1190.     which can be used from within xxxxcccc with the 'pipe' command, or from com-
  1191.     mand mode with the '$' command,    or using the examples under the
  1192.     _b_i_n_d__s_c_r_i_p_t command above.
  1193.  
  1194.    _D_e_b_u_g_g_i_n_g
  1195.     There are three    varieties of debugging in xxxxcccc.  The script command (set
  1196.     debug "on" or set debug    "off") will control echoing of each line of a
  1197.     script to the screen.
  1198.  
  1199.     If the program was compiled with DEBUG set to 1    in xc.h, all screen
  1200.     output will be captured    in a file called _d_e_b_u_g._l_o_g in the current
  1201.     directory, providing that it exists before entering xxxxcccc,,,,    and providing
  1202.     that output is not being diverted to a current capture file. The
  1203.     _d_e_b_u_g._l_o_g file is overwritten each time    xxxxcccc is run.
  1204.  
  1205.     If you forgot to turn on capturing, if the program was compiled    with
  1206.     DEBUG set to 1,    and if _d_e_b_u_g._l_o_g exists, all is    not lost: your session
  1207.     is recorded in _d_e_b_u_g._l_o_g.
  1208.  
  1209.     Note that capturing to files is    turned off when    exiting    terminal mode,
  1210.     and this includes running the built-in B+ or XMODEM protocols.
  1211.  
  1212.     Finally, in the    xcb+.c module, there is    a CIS_DEBUG definition line
  1213.     which is normally commented out. If this definition is uncommented,
  1214.     then a B+ transfer will    record every byte in a file called _x_c._l_o_g.
  1215.     This file is created if    needed,    in the current directory, and overwrit-
  1216.     ten on each run    of xxxxcccc.
  1217.  
  1218. Exit Codes
  1219.     0000  Successful, uneventful completion.
  1220.  
  1221.     1111  Error in command-line arguments.
  1222.  
  1223.     2222  Failure in forking to execute a command or run a shell.
  1224.  
  1225.     3333  No modem port specified on the command line,    or contained in
  1226.        the environment variable MODEM.
  1227.  
  1228.     4444  Inability to    create a LCK..file for the specified port.
  1229.  
  1230.     5555  Inability to    open the specified port.
  1231.  
  1232.     6666  No environment variable TERM    has been set.
  1233.  
  1234.     7777  No entry for    the current TERM setting in /etc/termcap.
  1235.  
  1236.     8888  Problem caused by the 'ungetty' program.
  1237.  
  1238. Copyright
  1239.     XXXXcccc and its source files    and sample scripts and manual page are Copy-
  1240.     right 1993 by Jean-Pierre Radley.
  1241.  
  1242.     Permission is granted to the public to use this    code in    any manner,
  1243.     without    any warranty, implied or otherwise, of fitness for a particular
  1244.     purpose.
  1245.  
  1246.     By virtue of a restriction previously placed upon all code derivative
  1247.     from xxxxccccoooommmmmmmm, the    xxxxcccc code    and associated files may not be    sold by    anyone
  1248.     to anyone, nor incorporated into any product that is not also free.
  1249.     It's OK    to transfer them for free.
  1250.  
  1251. Authors
  1252.     This manual page was written by    Fred Buck (1989) and Jean-Pierre Radley
  1253.     (1990, 1991, 1992, 1993).  XXXXcccc itself is    the product of many synergistic
  1254.     wise minds. See    the README document.
  1255.  
  1256. Version
  1257.     This edition of    the manual is for XC version 4.3 JPRadley 11 Sep 1993.
  1258.  
  1259.  
  1260.  
  1261.  
  1262.  
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.  
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.